package com.googlecode.vmock.matchers;

import java.math.BigDecimal;

/**
 * Matcher is an object that accepts or rejects other objects based on logic implemented in {@link Matcher#matches(Object)} method.
 * <p>
 * Matchers are powerfull addition to the VMock. They allow user to mock not only single calls, but also sets of calls. For example, end-user wants to
 * mock a call to {@link BigDecimal#add(BigDecimal)} method so it throws exception when a zero is passed to it. Solution to this requirement is given
 * below:
 * 
 * <pre>
 * <code>
 * expect(as(BigDecimal.class).add(BigDecimal.ZERO)).andThrow(new RuntimeException());
 * </code>
 * </pre>
 * 
 * If the user wants to throw an exception for all the possible values, he is forced to mock this call for every possible {@link BigDecimal} instance,
 * which is simply not possible. This kind of problem can be solved by using a matcher which accepts all instances of a {@link BigDecimal}. The
 * one-liner that does it is shown below:
 * 
 * <pre>
 * <code>
 * expect(as(BigDecimal.class).add(anyBigDecimal())).andThrow(new RuntimeException());
 * </code>
 * </pre>
 * 
 * @author marcin.jagus
 */
public interface Matcher extends Comparable<Matcher> {

    /**
     * Matches this matcher against given value.
     * 
     * @param value Given value
     * @return <code>true</code> if this matcher matches against the given value
     */
    boolean matches(Object value);
}
